<?xml version='1.0'?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>

  <head>

    <title>Custom Formatting</title>

    <link href="../css/styles.css" rel="stylesheet" type="text/css"/>
  </head>

  <body>

    <h1>Overview</h1>

    <p>SoapTrace.Net provides a simple plug-in architecture allowing 
    custom formatting of the soap message text in the main window.</p>

    <p>This feature grew out of the need to handle some misuse/abuse of 
    soap web services on one project. Messages were sent with xml sent 
    as strings instead of complex types, making the xml difficult to 
    read with character encodings such as &amp;gt; and &amp;lt; 
    throughout the text. Certain messages also had their xml strings 
    gzipped and then base64 encoded to reduce bandwidth, which made it 
    impossible to read the contents using Microsoft's Soap Trace 
    utility.</p>

    <p>A custom formatter is passed the soap request and response and 
    allowed to format the text that is displayed in the main 
    SoapTrace.Net's window.</p>

    <h1>Implementation</h1>

    <ul>

      <li>Create a new .Net assembly library (dll).</li>

      <li>Add a reference to the SoapTrace.Core.dll assembly.</li>

      <li>Create a class that implements the 
      SoapTrace.Core.Formatters.IMessageFormatter interface.</li>

    </ul>

    <h2>IMessageFormatter</h2>

    <p>

      <pre>
 public interface IMessageFormatter
 {
  /// Formats the soap request.
  ///
  /// param name="server" - The host name of the server 
  /// or the IP address.
  /// param name="uri" - The URI of the request
  /// param name="webServiceName" - The web service name.
  /// param name="webMethod" - The web service operation.
  /// param name="message" - The message request.
  /// returns - A formatted soap request that will
  /// be displayed in the SoapTrace's GUI.
  FormattedText FormatRequest( string server,
   string uri, 
   string webServiceName, 
   string webMethod, 
   ISoapMessage message );


  /// Formats the soap response.
  ///
  /// param name="server" - The host name of the server 
  /// or the IP address.
  /// param name="uri" - The URI of the response.
  /// param name="webServiceName" - The web service name.
  /// param name="webMethod" - The web service operation.
  /// param name="message" - The message response.
  /// returns - A formatted soap response that will
  /// be displayed in the SoapTrace's GUI.
  FormattedText FormatResponse( string server,
   string uri, 
   string webServiceName, 
   string webMethod, 
   ISoapMessage message );

  /// The name of the message formatter.  This name
  /// will be displayed in the View menu allowing
  /// this formatter to be selected.
  string Name{ get; }

  /// Returns whether or not the message formatter
  /// can be configured.
  bool IsConfigurable{ get; }

  /// Returns a configuration editor interface so the
  /// message formatter can be configured.  If no 
  /// configuration is required, return null.
  IConfigurationEditor ConfigurationEditor{ get; }
 }
</pre>
    </p>

    <h2>IConfigurationEditor</h2>

    <pre> /// Interface that allows a message formatter to  
 /// configure itself. 
 public interface IConfigurationEditor 
 { 
  /// Shows the config editor main dialog. 
  /// param name="owner" - The owner of the dialog. 
  void Show( IWin32Window owner ); 
 }</pre>
    <p>The configuration dialog is displayed when the user opens up the 
    Tools-&gt;Options dialog, selects the custom formatter from the 
    list and clicks the Options button.</p>

    <h2>Formatted Text class</h2>

    <p>This is the object that is returned by the formatter and used by 
    SoapTrace.Net to colour the text in the main window. The main 
    methods that will typically be used are:</p>

    <pre>   
  /// Appends a piece of text to the existing 
  /// formatted text.   
  ///  
  /// The text will have the colour specified when the  
  /// FormattedText class was created.
  public void Append( string text ) 


  /// Appends a piece of text to the existing 
  /// formatted text.   
  /// 
  /// param name="text" - A string to append.
  /// param name="colour" - The colour of the text. 
  public void Append( string text, Color colour )</pre>
    <h1>Configuration</h1>

    <p>In order for the custom formatter to be loaded by SoapTrace.Net 
    it needs to be added to the SoapTrace.exe.config file.</p>

    <pre>  &lt;messageFormatters&gt; 
   &lt;messageFormatter type="SoapTrace.Core.Formatters.SoapMessageFormatter, SoapTrace.Core"/&gt; 
  &lt;/messageFormatters&gt;</pre>
    <p>Adding another messageFormatter element with the type attribute 
    set to the string "TypeName, AssemblyName", where TypeName is the 
    name of the type that implements the IMessageFormatter interface, 
    and "AssemblyName" is the assembly where the custom formatter can 
    be loaded from.</p>

  </body>

</html>

